Steps to Version Your Shared Library 


1. Introduction 

With the enhancement and evolution of software, there can be growing pains, especially when an existing 
base of software depends upon earlier functionality. When changes are made to software libraries, estab¬ 
lished software engineering practices indicate making compatible changes such that installed software 
investment is preserved. Shared libraries provide a great challenge in this regard as old software dynami¬ 
cally binds with new shared libraries. When changes would break compatibility, versioning provides a 
mechanism to deliver new functionality while providing compatibility for existing applications. This paper 
explores the reasons and the techniques that should be employed to version a shared library using whole 
library versioning, also known as V.4 versioning. Although it provides steps to consider, it is not intended to 
be a complete recipe, rather steps to consider when a shared library versioning in considered as part of a 
development plan for a particular library. 


1.1 Terms and Definitions 

This paper uses the following terms as a common basis for discussion. 

Binding 

The process the dynamic loader goes through populating a process’ procedure linkage tables and 
data linkage tables with the addresses of shared library routines and data. When a symbol is bound, it 
is accessible to the program. 

Compatible 

This paper considers compatibility from the stand point of the software expected to operate. And for¬ 
ward or backward compatibility is in terms of moving that software forward or backward on releases. 
With that, this paper defines the two terms as follows: 

Backward Compatible 

The ability to take software compiled on a release and expect it to operate correctly on an earlier 
release of software. Software is usually not designed with this compatibility in mind. 

Forward Compatible 

The ability to take software compiled on a release and expect it to operate correctly on future releases 
of the host system. Software is usually designed this way; compatibility with future releases is an 
implied requirement. 

Deferred Binding 

The process of waiting to bind a procedure until a program references it. Deferred binding can save 
program start-up time. Compare with “Immediate binding.” 

Dependent Library 

When creating a shared library with id, you can place additional shared libraries on the load line using 
the -1 option. The created shared library has a dependency on the other referenced libraries. When 
the first library is loaded, the other “supporting” libraries will also be loaded. It is important to note that 
the supporting library’s current version is made a dependency for the first library. 

Dynamic Loader 

Code that attaches a shared library to a program. 



Explicit loading 

The process of using the shl_load () function to ioad a shared iibrary into a running program. The 
iibrary is dynamicaiiy ioaded as part of the shi_ioad () processing. 

Export Table 

A iist of symbois in a shared iibrary avaiiabie for other moduies. 

Immediate Binding 

By defauit, the dynamic ioader attempts to resoive symbois when they are referenced. By using Imme¬ 
diate Binding, aii routines and data wiii be bound when the iibrary is ioaded. For impiicitiy ioaded iibrar- 
ies this binding happens at program start-up. 

Implicit Loading 

Occurs when the dynamic ioader automaticaiiy ioads any required iibraries when a program starts exe¬ 
cution. Compare with “expiicit” ioading. 

Import Stub 

A short code segment generated by the iinker for externai references to shared iibrary routines. 

Incomplete Executable 

An executabie (a.out) fiie that uses shared iibraries. It is “incompiete” because it does not actuaiiy con¬ 
tain the shared iibrary code that it references; instead, the shared iibrary code is attached when the 
program runs. 

Position-Independent Code (PIC) 

Object code that contains no absoiute addresses. Aii addresses are specified reiative to the program 
counter or indirectiy through the iinkage tabie. Position-independent code can be used to create 
shared iibraries. 

Versioning 

The methodoiogy and capabiiity of one object referencing a certain vintage of another object based 
upon when the two objects were iinked together. This capabiiity aiiows for compatibiiity by providing an 
unchanging binding between objects even when new vintages of objects are created. 



2. Shared Library Background 

2.1 What is a shared library? 

An HP-UX shared library is a bound collection of routines and data used by other software modules. 
When a shared library is loaded, either implicitly when a program is started, or explicitly via the 
shi_ioad () routine, it is mapped into the process’s address space by the dynamic loader. Several appli¬ 
cations can access the same code space of the shared library, hence the name shared library. Applica¬ 
tions built with shared libraries do not have copies of routines and data from the shared library, instead they 
have an import table of symbols to be satisfied by the shared library when the application is run. 

Shared library symbols available for use by other modules are provided in an export table. The dynamic 
loader resolves access symbols, either when the library is loaded or the first time a symbol is accessed. 
The default is to bind symbols when they are first accessed, that is deferred binding. 

One obvious benefit of shared libraries is that they can reduce the amount of disk and memory required. 

2.2 What is V.4 Versioning? 

Library level versioning, also known as V.4 versioning, is a technique where the whole library is replaced 
with an updated library. This means that there are multiple complete libraries, one with the latest behavior 
and feature set and one or more previous versions with older behavior. A symbolic link is used to point to 
the latest library using a standard name, so that the programmer doesn’t need to be concerned about 
which version is the current version. By convention, library names end with a . numeric suffix (e.g. .1, .2, 
etc.) The latest library version has the largest numbered suffix. The standard library name ends in a .si 
suffix, and it will be a symbolic link pointing at the latest numbered library. 

At a high level, a shared library is versioned by incrementing the numeric suffix and changing the . si sym¬ 
bolic link to point to the new name. There are other considerations and details covered later in this paper. 



3. Why Version your Shared Library? 

Versioning of a shared iibrary shouid not be done capriciousiy as it compiicates the amount of support 
required for a iibrary by having a second version. Compiications can aiso spiii over to other iibraries if a 
dependency reieationship exists between the two iibraries. 

3.1 Incompatible Changes 

Libraries, areusuaiiy required to grow and change as a resuit of ever increasing tasks the software is 
required to perform. Many times software evoiution can be done in such a way to be compatibie, which is 
desirabie. At other times it is not possibie or desirabie to maintain compatibiiity, possibiy due to new speci¬ 
fications, standard compiiance or technicai constraints. 

3.1.1 Determining if your Change is Incompatibie 

Shared iibrary compatibiiity is maintained when an oider software moduie, either a program or another 
shared iibrary, stiii operates correctiy with a shared iibrary. Changes to functions and data that are not 
exported do not break compatibiiity. Changes to exported functions and data eiements cause compatibiiity 
probiems with the moduies that import those symbois. Aithough not absoiute, the foiiowing describe 
incompatibie changes: 

For functions, the type of changes that are typicaiiy incompatibie inciude: 

• Changing the number of parameters, parameter order, types or meanings. 

• Changing return vaiue types or meanings. 

• Changing a function to take advantage of another iibrary’s change. 

• Depending on another shared iibrary that has changed, even if you don’t know why theother iibrary 
has changed. 

• Changing macro impiementations of functions in pubiic header fiies to be incompatibie with previ¬ 
ous macros. 

• Repiacing a pubiic function with a macro, thus removing the function as an exported symboi. 

For exported data eiements, the foiiowing changes are typicaiiy incompatibie: 

• Changing the size. 

• Changing the defauit vaiue. 

• Changing the eiement iocations in structures. 

• For C-i-i- iibraries, changing the type of a function parameter, even if the size remains the same. 

• Changing interface variabie types. 

• Changing non-opaque eiements of structures in pubiic header. 


In generai, if the new version of a shared iibrary can be used in piace of the oid shared iibrary, compatibiiity 
is maintained. 



3.1.2 Making Changes Compatible 


Before considering iibrary versioning, it wouid be good to iook at the possibiiity of aitering a change to 
make it compatibie. It may be possibie to add new entry points or data types to expand the behavior of 
functions without affecting compatibiiity. Even if it invoives more work to make a change compatibie, it wiii 
iikeiy be iess effort when the costs of versioning, and testing and maintain both versions are considered. In 
general, the following types of changes do not break compatibility: 

For exported functions: 

• Adding a new exported function to handle new behavior 

• If a function has an “operations type” argument, adding new operations. 

• Increasing the domain and/or range of argument and return values if the old domain and range 
work as they did previously. 

• Adding new parameters if those parameters are not needed by the function when called in a previ¬ 
ously acceptable manner. 

• Adding new argument types to functions that parse arguments with stdarg's or vararg's 
based upon other criteria. 

For exported data elements: 

• Increasing the range of values as long as the new values were previously represented with unde¬ 
fined behavior. 

• Adding new exported data elements. 

For header files associated with a shared library 

• Changing opaque data structure elements as long as non-opaque element locations are not 
changed and the overall size of the structure is unchanged. 

• Adding new #define constants or macros. 

• Adding new typedef’s or variable types. 

3.2 Changes in Other Libraries 

Sometimes the changes in one library may cause changes in other libraries as well. This can be due to 
sudden interface changes or that an enhanced interface needs to be used consistently by both direct and 
indirect users of a library. It may also come about simply by recombining the dependent library. This would 
be due to changes in the header files associated with the versioning library. 



3.2.1 Latent Versioning 


Even if the immediate changes of a versioning iibrary do not cause a dependent iibrary to version, it cre¬ 
ates a situation where versioning may be required in the future. This can be expiained in fig 1. In the dia- 
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FIGURE 1. Latent Versioning 
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gram, iibA versions at reiease X, but it is determined that iibB doesn’t need to vefrsion. This creates the 
case where a singie iibrary, iibB.1 is expected to operate correctiy with both iibA.1 and iibA.2. Even though 
there are no immediate difficuities with this situation, there is the possibiiity of future versioning of iibB 
when it depends on API’s or capabilities only available in IibA.2. 

Both library providers need to monitor this situation, not only at the time of IibA versioning, but until the 
point when IibB versions as well. 



4. How to Version your Library 

Once you determine you need to version your iibrary, what step do you need to go through to version your 
iibrary. The practice for naming a new version of a iibrary is to use the oid name of the iibrary with a 
numeric suffix one greater than the previous version (e.g. use libxyz . 2 when versioning libxyz. l). If 
your iibrary is deiivered directiy with a . si suffix, see section 4.4.1 beiow. 

4.1 Source Tree 

For the most part, your source fiies shouid not be affected by versioning. Most iikeiy you want to symboii- 
caiiy tag the appropriate revision of aii fiies used to buiid the previous version of the iibrary. This wiii provide 
a means of recreating that iibrary shouid a patch be required. This tagging shouid take piace before any 
other step. 

4.2 Building the New Library 

The dynamic ioader reiies on the internai name of a iibrary to resoive which fiie to use at runtime. The 
internai name is set with the “+h internai_name’ option to the id command. Change your makefiie or 
buiid script to have the new versions name as the argument to the +h option. 

4.3 Delivering the New Library 

Normaiiy the new version of iibrary wiii be deiivered in the same iocation that the oid one was. Since the 
iibrary names have different suffixes, there isn’t a name coiiision. You aiso want to make sure that your oid 
iibrary is deiivered in future reieases, both for instaiiation and for updates. The oid iibrary provides run-time 
support for software previousiy iinked with it. 

4.3.1 Handling the Old Library 

The oid version of the iibrary needs to be preserved so that you can provide it on the instaiiation media. 
You wiii aiso need to keep around an appropriate oider compiiation/testing environment for the oid iibrary 
so that you are abie to support the iibrary. This is not much different than supporting a non versioned 
iibrary, as you need to keep a deveiopment environment corresponding to the oidest reiease you support. 

The oid version of the iibrary needs to be deiivered so that oid appiications continue to operate correctiy. 
You may want to make instaiiation of the oid iibrary optionai if those instaiiing the iibrary have a ciear way of 
knowing whether or not they need the oid iibrary version. 

4.3.2 Symilnks 

As part of versioning your iibrary, you want to make sure the “.si” symiink points at the new iibrary. If you 
previously delivered your library as libxyz . si, then see section 4.4.1 for more details on how to create 
the initial version of your library. For your library libxyz, there should be a symbolic link libxyz . si that 
point at the new library version. For example if you are changing from version 1 to version 2, your library’s 
entries in the installation directory before and after versioning will look like the files found in the directory 
listing below: 



Before versioning iibxyz 


-r-xr-xr-x 

1 

bin 

bin 

21312 

Dec 

1 

1994 

/usr/lib/Iibxyz.1 


Irwxr-xr-x 

1 

bin 

bin 

17 

Dec 

1 

1994 

/usr/lib/Iibxyz . si 

-> /usr/lib/libxyz.1 

After versioning iibxyz from version 1 to version 

2 


-r-xr-xr-x 

1 

bin 

bin 

21312 

Dec 

1 

1994 

/usr/lib/Iibxyz.1 


-r-xr-xr-x 

1 

bin 

bin 

32854 

Jul 

11 

1995 

/usr/lib/Iibxyz.2 


Irwxr-xr-x 

1 

bin 

bin 

17 

Jul 

11 

1995 

/usr/lib/Iibxyz.si 

-> /usr/lib/libxyz.2 


After the versioning was compieted, a new fiie existed, iibxyz.2, and the symboiic iink, iibxyz.si, now points 
at that version. 

4.4 Other Considerations 

4.4.1 Pre V.4 Libraries 

If you deiiver your iibrary as iibxyz . si and haven’t been buiiding it with the +h option, then you’ii need to 
change how you deiiver the oid iibrary as weii as the new iibrary. The oid iibrary shouid be deiivered as 
Iibxyz . 0 in the same directory that you were deiivering the . si version. The new iibrary shouid be deiiv¬ 
ered as Iibxyz . 1 and you shouid create a symboiic iink, iibxyz . si that points to iibxyz . i. you 
shouid aiso foiiow the other steps outiined in sections 4.2 and 4.3. 

4.4.2 Source Compatibility 

When you make changes that necessitate versioning, you stiii want to consider the source impiications to 
those who use your iibrary. Versioning provides for binary compatibiiity for existing appiications, therefore if 
you make your changes in a source compatibie manner, you provide a migration path for aii users of your 
iibrary. Sometimes the nature of you changes do not aiiow for 100% source compatibiiity. Your goai then, 
shouid be to minimize to amount of rework that users have to go through to compiie with the new iibrary. 

If you are not able to make your changes in a source compatible manner, provide clear documentation that 
outlines the changes needed to be made when using your library. 

4.4.3 Allowing for Future Development 

Since your newly versioned library doesn’t have a legacy code set to operate with, you have some freedom 
to make changes with the future direction of your library in mind. You’ll need to consider these expansion 
related changes in light of providing source compatibility, but it is usually better to version your library less 
often due to the development and support costs. Therefore, if you are aware of interface modifications 
needed to support future technology, make them now to save those the costs of a second versioning effort. 

Some of the techniques for allowing for future development that you may consider: 

Structure Growth - Provide space in structures for future elements. This is especially important for struc¬ 
tures that are allocated directly by the calling code. 

Constructor Functions - An even better method for handling future structure growth is to provide func¬ 
tions that are used to allocate instance of interface structures for your library. Provid¬ 
ing such function make it easier to extend structures when all structures are created 
this way, as code calling you library doesn’t know the sizeof your structures. 



Accessor Methods - For the most part, it is better to provide an expandabie macro or function to access 
structure vaiues, especiaiiy flags and bit masks. This insuiates somewhat the user of a 
structure from its impiementation, thus aiiowing for future expansion. 

Versioning Structures - If you are making structure changes, you may want to provide a fieid used to ver¬ 
sion the structure iayout. That way, you can change the structure and have different 
code read/write the various versions of the structure. 

Expandable Macros - Aithough macro often simpiify the written of code through substitution, they have 
greater compatibiiity impiications than functions, as macros contents are substituted 
and compiied in-iine into the caiiing object code. One method for providing for future 
macro changes is to provide a macro that uses a iibrary or structure conditionai vari- 
abie to predicate the macro impiementation or to caii an equivaient function. For 
exampie consider a macro used to access the fiie descriptor of some structure S: 

#define get_file_desc(S) ((S->version == 1)?S->fd:GetFD(S)) 

The fieid version is a structure versioning fieid and GetFD ( ) is a function to get a 
fiie descriptor for any version of the structure. This macro is basicaiiy a quick impie¬ 
mentation for version 1 of a structure. If the structure version is changed, then the 
function is caiied. 

4.4.4 Communicating Changes 

If you version your iibrary, you need communicate with those deveiopers who depend on your iibrary the 
changes you made to the iibrary and any effects the versioning wiii have on the way to use your iibrary. 
Some of the issues you may need to communicate inciude: 

• Libraries that may or may not be used with the new version of the iibrary. 

• The compatibiiity the iibrary provides when used in a iegacy environment. This shouid inciude the 
support for oid hardware, obsoieted features, or previous data formats, etc. 

• Any changes to compiie or iink with the new iibrary. Inciude source incompatibiiities, changes in 
inciude fiie usage. 

• The capabiiities and features the new iibrary version provides. 

4.4.5 Message Catalogs 

If you library is localized, you will need to decide how to handle message catalogs. This is primarily due to 
changing messages can affect both the old and new library. Since the old library is some what fixed in time, 
the messages accessed by the old library do not change. If you use .msg files to store your messages, 
you can add comments to all messages referenced by the old library. You can also adopt the policy that 
when changing a message, you also change the message number. If you use insertmesg, you may want 
to specify a new set number to use with new messages. That way you correlate your message sets with 
the library version. 

4.4.6 Explicitly Loaded Libraries 

For shared libraries loaded explicitly via shi_ioad {) , you may need to handle them a little differently from 
an implicitly loaded library. These libraries typically are used to implement some variable behavior, either 
based upon attached hardware, some environment variable or the like. 

If you are versioning a library that dynamically loads another shared library, you will need to consider care¬ 
fully the effect on the changes to the versioning library to the explicitly loaded library. Consider again figure 



1 as the same kind of dependency exists between the two iibraries. If the dynamicaiiy ioaded iibrary, iibB in 
the figure, needs to change any time after iibA versions, there is the distinct possibiiity for incompatibiiities. 

If you end up versioning a expiicitiy ioaded shared iibrary, there may be some concerns as to how it is used 
in the oid version of the ioading iibrary. If the library has always been loaded with a name 
/some/path/libdynamic . si and is really a symbolic link to / some/path/libdynamic .1 or is a 
library that has never versioned, you will need to make provisions for uniquely loading the proper version. If 
you are versioning your explicitly loaded library for the first time, use the suffix “.1” with the library, e.g. 
/some/path/iibdynamic. 1. Also when you go to load the library, use the file name with the “.1” suffix. 

4.4.7 Removing Old Code 

Since you are versioning your library, it may be a time to remove code no longer required to be part of the 
library. For example if you have obsoleted some functionality or have used HP’s intra-library (routine level) 
versioning, versioning your library provides a good opportunity to remove such dead code. 

4.5 Testing 

After completing the tasks necessary to version your library, you need to verify its correctness. The normal 
library testing processes you go through should be sufficient to verify proper functionality of the library, but 
there are some special steps to verify that the versioning process was accomplished successfully. After the 
versioning is complete, you will have another library to test. 

4.5.1 Testing the Old Library 

To verify proper operation of the older library, you will need to execute test suites compiled with the old 
library on a system containing both the old and new library versions. Since those using your the old version 
of your library are not able to compile and link with it on the latest release, your tests need to be compiled 
and linked against the old library in a similar environment. In the same way you preserved the previous ver¬ 
sion of your library, you can preserve a compiled and linked copy of your test suite. Then to test the old ver¬ 
sion of the library, you install and run the old test suite without recompilation. 

Should you have to patch the old version of your library, you may need to be able to augment the test suite 
for the old library. This will likely require a earlier release environment to develop the old version of the tests 
much in the same way that bug fixes are made to the old library in an appropriate older release environ¬ 
ment. 

4.5.2 Testing the New Library 

The new library shouldn’t require testing beyond the normal qualification you go through to certify your 
library. You will need to watch for the latent versioning situation described in section 3.2.1, especially when 
future changes are made to the new library version. 



Summary 

With the requirements of software growing, especiaiiy in unforeseen ways, software deveiopment tech¬ 
niques need to be deveioped to maintain compatibiiity with iegacy systems whiie at the same time provid 
ing for growth to accommodate the future. V.4 versioning is a not to costiy method to provide for this 
compatibiiity and growth. Whiie other methods have been expiored, inciuding HP’s own routine ievei ver¬ 
sioning, the current state of the art for Unix systems is V.4 versioning. 

Aithough this papered outiines considerations and techniques to accompiish V.4 versioning, it shouid be 
understood that versioning is a technique that has its costs, in terms of disk space and support overhead 
For versioning to be successfuiiy empioyed, its must be used wiseiy. 
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